home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / macros / lollipop / comm.tex < prev    next >
Text File  |  1993-01-28  |  24KB  |  675 lines

  1. % Comm.tex copyright 1992 Victor Eijkhout
  2. %
  3. \Chapter Commands
  4.  
  5. \Section[sec:counters] Counters
  6.  
  7. Counters can be declared explicitly by the user, but more often they
  8. are defined automatically in some generic construct:
  9.  
  10. The \cs{Foo} defined by 
  11. \Ver>\DefineBar:Foo ... 
  12.     counter:i ...
  13.     Stop<Rev
  14.  
  15. will have a counter that counts in roman lowercase, and which is
  16. accessible as \refcs{FooCounter}. Everytime \cs{Foo} is used, this
  17. counter is increased by one.
  18.  
  19. The use of the \opt{counter} option is described
  20. in~\ref[sec:opt:counter].
  21. Here are the commands for explicit manipulation of counters.
  22.  
  23. \SubSection[sec:counter:repr] Allocation and representation
  24.  
  25. A counter is created by for instance
  26. \Ver>\NewCounter:Things<Rev
  27. This will create control sequence \cs{ThingsCounter} that will print
  28. the value of the counter.
  29. The counter will usually be printed as an Arabic numeral, but other
  30. counter representations can be specified by
  31. \refcs{CounterRepresentation}. Here are their codes: \Description
  32. \item 1
  33. numeric
  34. \item a
  35. lowercase character
  36. \item A
  37. uppercase character
  38. \item i
  39. lowercase roman
  40. \item I
  41. lowercase roman
  42. \>
  43. for instance
  44. \Ver>\CounterRepresentation:Things=i<Rev
  45. will cause \cs{ThingsCounter} to print a lowercase Roman numeral.
  46.  
  47. However, a call such as
  48. \Ver>\CounterRepresentation:Theorem=Lemma<Rev
  49. will make the \cs{TheoremCounter} a synonym of an earlier created
  50. \cs{LemmaCounter}
  51.  
  52. \SubSection Counter manipulation
  53.  
  54. The following commands can be used to manipulate counters, both when
  55. they are created by hand using \refcs{NewCounter} and when they were
  56. generated automatically in some generic construct:
  57.  
  58. With \refcs{StartCounter} reset the counter to one:
  59.  \Ver>\StartCounter:things<Rev
  60.  
  61. With \refcs{StepCounter} increase the counter by one:
  62.  \Ver>\StepCounter:things<Rev
  63.  
  64. With \refcs{BackStepCounter} decrease the counter by one:
  65.  \Ver>\BackStepCounter:things<Rev
  66.  
  67. With \refcs{SetCounter} set the counter to some specified value:
  68.  \Ver>\SetCounter:things=5<Rev
  69.  
  70. With \refcs{AddToCounter} increase the counter by some
  71. specified value:
  72.  \Ver>\AddToCounter:things=7<Rev
  73.  
  74. The last two commands accept names of numerical parameters, for
  75. instance the value of a counter:
  76.  \Ver>\NewCounter:Favourite
  77. \AddToCounter:things=FavouriteValue<Rev
  78. More about this `value' thing in the next section.
  79.  
  80. \SubSection What do you get when you define a counter?
  81.  
  82. After you define a counter as \Ver>\NewCounter:MyThings<Rev there are
  83. two commands that it is important to distinguish between. First of
  84. all, \cs{MyThingsCounter} gives the {\it printed\/} value of the
  85. counter. This is the command that you will use mostly. It uses
  86. whatever representation you have specified for the counter, or plain
  87. Arabic numerals if haven't specified anything.
  88.  
  89. Secondly, \cs{MyThingsValue} gives the value of the counter. You can
  90. not use this command on its own: you will get a `number expected'
  91. error.
  92.  
  93. \SubSection Counter hierarchies
  94.  
  95. Often counters are related to each other. For instance, when a new
  96. section begins, the subsection counter has to be reset. The same may
  97. be true for equation counters. In Lollipop such a relation is
  98. indicated by a call to \refcs{GoverningCounter}, for instance
  99.  
  100. \Ver>\GoverningCounter:SubSection=Section<Rev
  101.  
  102. All of the counter manipulation commands applied to a governing
  103. counter will cause all governed counters to be reset. Such a reset
  104. also occurs if the counter was created in some generic construct.
  105.  
  106. For examples, see section~\ref[sec:head:examples].
  107.  
  108. \SubSection Referencing counters
  109.  
  110. All counters that are declared as part of a generic construct, or
  111. explicitly through \refcs{NewCounter} automatically become the current
  112. reference when they are altered. Thus \ver>\label[bar]> will make
  113. \ver>\ref[bar]> refer to the value of the counter most recently
  114. changed. The way the counter is referenced can be altered by the
  115. \opt{label} option in generic constructs; see
  116. section~\ref[sec:opt:label].
  117.  
  118. For generic constructs with a counter no explicit \refcs{label} commands
  119. need to be given; such commands take an optional argument with the
  120. label key:
  121. \Ver>\Section[sec:examples] Examples<Rev
  122.  
  123. \SubSection Adaptive counters
  124.  
  125. It may happen that you want to compute a value during one run of
  126. \TeX, and use it in the next. An example is the fact that this manual
  127. states the total number of pages on the title page. For this you can
  128. use \refcs{AdaptiveCounter}
  129.  \Ver>\AdaptiveCounter:LastPage<Rev
  130. which is like \cs{NewCounter}, except that the value of this counter
  131. gets written to the \file{.aux} file.
  132.  
  133. There are two ways of setting an adaptive counter: you can simply use
  134. it in some construct (for instance through a counter synonym;
  135. section~ref[sec:counter:repr]), or you can set it explicitly, for
  136. instance as
  137.  \Ver>\SetCounter:LastPage=PageValue<Rev
  138. See how this manual does it.
  139.  
  140. \SubSection Examples of counter usage
  141.  
  142. Items start at the value of one, so if a starting value of zero is
  143. necessary, the following will work
  144. \Ver>
  145. \Enumerate \SetCounter:item=-1
  146. \item ...<Rev
  147.  
  148.  
  149. \ImpNote
  150.  
  151. \iSection The counter name
  152.  
  153. The \cs{count} register associated with a counter receives an internal
  154. name:
  155. \Ver>\def\counter@name#1{#1@C}<Rev
  156.  
  157. Also the following common abbreviations are provided:
  158. \Ver>
  159. \def\cs@counter@name#1{\csname#1@C\endcsname}
  160. \def\counter@@name#1{\CSname{#1@C}}<Rev
  161.  
  162. \iSection Allocation and representation
  163.  
  164. The user command \refcs{NewCounter} allocates a counter plus an
  165. associated `reset list':
  166. \Ver>
  167. \def\NewCounter:#1 {
  168.     \csarg\newtoks{#1@RL}
  169.     \csn #1@RL\ecs={}
  170.     \new@counter{#1}
  171.     }
  172. \def\new@counter#1{
  173.     \new@@counter{#1}
  174.     \CounterRepresentation:{#1}=1
  175.     \StartCounter:{#1}
  176.     }
  177.  
  178. \def\CounterRepresentation:#1=#2 {
  179.     \if\UndefinedCS{\counter@name{#2}}%is deze teller een synoniem?
  180.           \represent@counter{#1}{#2}
  181.     \else \@SynonymCounter{#1}{#2}
  182.     \fi}
  183. \def\represent@counter#1#2{
  184.     \edef\cs@e{@\if#2iroman\else
  185.        \if#2IRoman\else \if#2alcascii\else
  186.        \if#2Aucascii\else arabic\fi\fi\fi\fi}
  187.     \csarg\edef{\counter@repr{#1}}{\CSname{\cs@e}}
  188.     \csarg\edef{#1Counter}%
  189.       {\CSname{\counter@repr{#1}}\counter@@name{#1}}
  190.     }
  191. \def\@SynonymCounter#1#2{\edef\cs@b{%
  192.    \nxp\let\counter@@name{#1}=\counter@@name{#2}
  193.    \nxp\let\CSname{#1Counter}=\CSname{#2Counter}
  194.    \nxp\let\CSname{#1@RL}=\CSname{#2@RL}}
  195.     \cs@b
  196.     }
  197.  
  198. \@GenericOption{sharecounter}
  199.    {\CounterRepresentation:\@name=#1 }<Rev
  200.  
  201. \iSection Governing and resetting
  202.  
  203. A counter can be defined as being governed by another counter;
  204. whenever the other counter is manipulated, this counter is reset.
  205. The implementation is through `reset lists': every counter is added to
  206. the reset list of its governing counter, and whenever a counter is
  207. altered, everything in its reset list is reset.
  208. \Ver>
  209. \def\GoverningCounter:#1=#2 {\if\UndefinedCS{#2@RL}
  210.     \Emessage{No counter defined for `#2'}
  211.     \else\append@to@list{#2@RL}{\\#1;}\fi}
  212. \def\reset@subordinates#1{%
  213.     \def\\##1;{\start@counter{##1}}%
  214.     \the\csname #1@RL\endcsname  \let\\=\relax}<Rev
  215.  
  216. The command \cs{reset@subordinates} is executed by all user level
  217. commands:
  218. \Ver>
  219. \def\StartCounter:#1 {\handle@user@counter{#1}{start}{}}
  220. \def\StepCounter:#1 {\handle@user@counter{#1}{step}{}}
  221. \def\BackStepCounter:#1 {\handle@user@counter{#1}{back@step}{}}
  222. \def\SetCounter:#1=#2 {\handle@user@counter{#1}{set}{#2}}
  223. \def\handle@user@counter#1#2#3%
  224.    {\if\UndefinedCS{\counter@name{#1}}
  225.           \Wmessage{Unknown counter: #1}
  226.     \else \csarg\global{#2@counter}{#1}{#3}%
  227.           \reset@subordinates{#1}\define@reference{#1}%
  228.     \fi}<Rev
  229.  
  230. The system level commands have no further complications.
  231. \Ver>
  232. \def\step@counter#1%
  233.    {\increase@value{\counter@name{#1}}\@ne}
  234. \def\back@step@counter#1%
  235.    {\increase@value{\counter@name{#1}}\m@ne}
  236. \def\start@counter#1%
  237.    {\set@value{\counter@name{#1}}\z@}
  238. \def\set@counter#1#2%
  239.    {\set@value{\counter@name{#1}}{#2}\relax}<Rev
  240.  
  241. \ImpNoteStop
  242.  
  243. \Section[sec:font] Font selection
  244.  
  245. In \Lollipop, choosing a font is done through three parameters:
  246. \Description\item Typeface
  247. A collection of related styles and sizes. The typeface is set by the
  248. command \refcs{Typeface}.
  249. \item Style
  250. Italic, bold, roman, typewriter. You know. The style is set by the 
  251. command \refcs{Style}.
  252. \item PointSize
  253. The size of a font in typographical points ($72.27$ per inch).
  254. The pointsize is set by the command \refcs{PointSize}.
  255. \>
  256.  
  257. The most common change of font is a change in style. Therefore,
  258. issuing a command such as \Ver>\Style:bold<Rev immediately changes
  259. the font to the bold of the current typeface in the current pointsize.
  260.  
  261. However, issuing a command such as \Ver>\Typeface:GoudyOldStyle<Rev
  262. or \Ver>\PointSize:28<Rev will not change the font, since such
  263. changes are usually accompanied by a change in style. In case that an
  264. immediate switch is necessary, the command 
  265. \refcs{SetFont} can be given.
  266. This evaluates the current value of the typeface, style, and
  267. pointsize commands, and sets the font accordingly.
  268.  
  269. A number of typeface names have been predefined in \Lollipop,
  270. however, in order to print them your printer (software) must have them
  271. available.
  272.  
  273. \Example
  274. \SerifFace \PointSize:12 
  275. \Style:roman This \Style:italic sentence \PointSize:10 has
  276. \SetFont way \SansFace \Style:roman too \SetFont many 
  277. \PointSize:12 \SetFont font \Style:bold changes.
  278. \ExampleStop 
  279.  
  280. (The commands \cs{SerifFace} and \cs{SansFace} are defined in
  281. the master file of this manual, and serve to make this manual
  282. formattable on any system.)
  283.  
  284. \SubSection Relative size changes
  285.  
  286. Apart from setting the pointsize explicitly, it is also possibly to
  287. make size changes relative to the current size. For instance,
  288. \refcs{PointSizeLarger} and \refcs{PointSizeSmaller} with an optional
  289. argument indicating the size of the change can be used. These
  290. commands are not cumulative.
  291.  
  292. \Example
  293. \SerifFace
  294. \PointSize:9 \SetFont Every once in a while,\SaveFont
  295. \PointSizeLarger[2] shouting \PointSizeLarger helps.
  296. \PointSizeSmaller[2]But most of the times it doesn't.
  297. \RestoreFont Unfortunately.
  298. \ExampleStop
  299.  
  300. Similar to the changes in mathematics mode to script and scriptscript
  301. size, the same relative changes are available in text mode through
  302. the control sequences \refcs{script} and \refcs{scriptscript}. 
  303. The control
  304. sequence \refcs{normal} can be used to restore the default size.
  305.  
  306. Here is one application of such relative changes:
  307. \Ver>
  308. L\kern -.3em\raise .35ex\hbox {\script A}\kern -.1em\TeX<Rev
  309. which gives definition of the \LaTeX\ logo that is independent
  310. of typeface, size and style.
  311.  
  312. The relative sizes of script and scriptscript fonts are by default at
  313. $70\%$ and $50\%$, but they can be set explicitly by
  314. \Ver>\PointSizeScriptSizes:10=10,7,5<Rev
  315. This also gives the possibility to have the \cs{normal} size to be
  316. different from the surrounding pointsize.
  317.  
  318. \SubSection Typeface definition
  319.  
  320. Defining a typeface means telling \Lollipop\ how the external font
  321. name, that is, the name of the \n{tfm} file, is to be constructed from
  322. the internal parameters. The command \refcs{DefineTypeface} takes four
  323. parameters and an optional fifth. The parameters are in sequence
  324. \Enumerate\item The internal name of the typeface: the name that is
  325. given to the \cs{Typeface} command.
  326. \item The root of the external file name. It is assumed that all
  327. font names of different styles and sizes are constructed by appending
  328. characters to this base.
  329. \item Suffixes corresponding to the styles that are available.
  330. \item Suffixes corresponding to the sizes that are available.
  331. \>
  332.  
  333. Here is the definition of the Computer Modern typeface:
  334.  
  335. \Ver>
  336. \DefineTypeface{ComputerModern}{cm}
  337.     {roman:r; slant:sl; italic:ti; mitalic:mi; bold:bx; tty:tt;
  338.      default:r;}
  339.     {<6:5; <7:6; <8:7; <9:8; <10:9; <11:10; 
  340.      <12:10 \scaled\magstephalf;
  341.      <14:10 \scaled\magstep1; <16:10 \scaled\magstep2;
  342.      <20:10 \scaled\magstep3; >19:10 \scaled\magstep4;
  343.      default:10;}<Rev
  344.  
  345. Actually, not all combinations of styles and sizes are available.
  346. That's where the optional argument comes in. This argument can be
  347. used to specify with \TeX\ conditionals exceptional style/size
  348. combinations. Here some trickery is needed: internally the size is
  349. stored in \cs{F@size}, and in order to use this parameter we need to
  350. make the at-sign a letter temporarily.
  351.  
  352. \Ver>\makeatletter
  353. \DefineTypeface{Compu ...
  354.     ...
  355.     default:10;}
  356.     [\ifStyle:italic \ifnum\F@size<7 ti7\fi\fi
  357.      \ifStyle:tty \ifnum\F@size<8 tt8\fi\fi]<Rev
  358.  
  359. You may have noticed that this scheme is not all-powerful. Thus
  360. I~found it easier to move all Computer Modern sans serif fonts into a
  361. new typeface: \n{ComputerSans}.
  362.  
  363. For other typefaces specifying the size suffix may be much easier
  364. than for Computer Modern. For instance, here is the definition of the
  365. PostScript Helvetica typeface.
  366.  
  367. \Ver>\makeatletter
  368. \DefineTypeface{psHelvetica}{helv}
  369.     {roman:; italic:i; mitalic:i; bold:b; default:;}
  370.     {default: at \F@size pt;}
  371. \makeatother<Rev
  372.  
  373.  
  374. \SubSection Math fonts
  375.  
  376. Switching styles in math mode should be possible:
  377. $${\Style:bold x\Style:roman y}z$$
  378.  
  379. \SubSection Other font matters
  380.  
  381. The combination \refcs{SaveFont} with a subsequent 
  382. \refcs{RestoreFont} can
  383. be used to save and restore the current font.
  384.  
  385. An abbreviation for a font can be defined by
  386. \Ver>\DefineFont:name=face,size,style<Rev
  387.  
  388. Even if you don't use Computer Modern as your main typeface, the
  389. typewriter style is not bad, so a control sequence
  390. \Ver>
  391. \def\tt{\Typeface:ComputerModern \Style:tty }<Rev
  392. has been given that makes \refcs{tt} always refer to the
  393. \n{cmtt} fonts. You're at liberty to change this, of course.
  394.  
  395. \Section Baselineskip
  396.  
  397. Corresponding to a font size usually the baseline skip has to change.
  398. By default a fixed ratio of~$1.2$ for this is taken, for instance
  399. using a 12~point baseline skip for 10~point fonts. Changing the ratio
  400. can be done by
  401. \Ver>\BaselineSkipPointSizeRatio:1.3<Rev
  402.  
  403. If only for some specific size the baseline skip has to deviate from
  404. the default ratio, then this can be set by
  405. \Ver>\SetPointSizeBaselineSkip:9=12<Rev
  406.  
  407. \Section[sec:indent:control] Indentation Control
  408.  
  409. \SubSection To indent or not to indent
  410.  
  411. In most documents there is a general rule that all paragraphs indent
  412. unless a certain condition, or that they do not indent unless certain
  413. special conditions hold. For \Lollipop\ documents this is determined
  414. by the command \refcs{AlwaysIndent}, with values \n{yes}/\n{no}.
  415.  
  416. To override this default setting a command \refcs{Indent}
  417. (with values \n{yes}/\n{no}) exists, but that is mostly useful as an
  418. option in generic constructs, and even there it will not be used much.
  419. See section~\ref[sec:opt:indent] for options relating to indentation.
  420.  
  421. Important: never set \cs{parindent} to zero. Preventing indentation
  422. globally should be done through \ver>\AlwaysIndent:no>.
  423.  
  424. \SubSection[sec:basic-indent] Basic indent
  425.  
  426. There is a quantity \refcs{basicindent} that is used on the first
  427. indentation level (see the next section for an explanation of these
  428. levels). At the start of a document it is set to the then current
  429. value of \cs{parindent}. You can override that by
  430. \refcs{BasicIndentIsSet}: give
  431. \Ver>\BasicIndentIsSet:no<Rev before the \cs{Start} command.
  432.  
  433. This way, setting \cs{parindent} in the style definition controls the
  434. indentation in the whole document.
  435.  
  436. \SubSection Indentation levels; indentation size
  437.  
  438. When \Lollipop\ decides that text should be indented, it refers to a
  439. list of indentations for the exact amount. This list contains
  440. indentation amounts for each `level' of indentation: initially the
  441. level is one, and if you nest constructs that indent (for instance
  442. using a list inside a list) the level goes up one step per nested
  443. construct.
  444.  
  445. By
  446. default the indentation on different levels is a fraction of the
  447. \cs{basicindent}. Thus you can regulate the indentation on
  448. all levels simultaneously by resetting the \cs{basicindent}.
  449.  
  450. \Example
  451. \Distance:basicindent=15pt
  452. \DefineList:TestList item:left itemCounter item:stop Stop
  453. \TestList\item Level one \TestList\item Level two
  454. \TestList\item Level three\>]
  455. \Distance:basicindent=25pt
  456. \TestList\item Level one \TestList\item Level two
  457. \TestList\item Level three\>]
  458. \ExampleStop
  459.  
  460. The amount of
  461. indentation on a certain level can be set explicitly with
  462. \refcs{LevelIndent}.
  463.  
  464. \Example
  465. \Distance:basicindent=15pt
  466. \LevelIndent:2=20pt
  467. \DefineList:TestList item:left itemCounter item:stop Stop
  468. \TestList\item Level one \TestList\item Level two
  469. \TestList\item Level three\>]
  470. \ExampleStop
  471.  
  472. \SubSection Manipulating the indentation level
  473.  
  474. Every once in a while it can be useful to move to a next indentation
  475. level, or to return to a previous level. For this
  476. the two commands \refcs{PushIndentLevel} and \refcs{PopIndentLevel} are
  477. available. One application is for `interrupted lists':
  478.  
  479. \Example
  480. \Itemize\item One
  481. {\par\PopIndentLevel Interrupted text!\par}
  482. \item Two\>
  483. \ExampleStop
  484.  
  485. See chapter~\ref[chap:external-files] for examples of the use of
  486. \cs{PushIndentLevel}
  487.  
  488. \Section Margins
  489.  
  490. By default, \Lollipop\ tries to keep straight margins. You can change
  491. its mind about that by \refcs{FlushRight} and \refcs{FlushLeft}
  492. which are tests:
  493. \Ver>\FlushRight:no \FlushLeft:no<Rev
  494. If the margins are not flush, the stretchable white space used
  495. is \refcs{rightmarginstretch} and \refcs{leftmarginstretch},
  496. which can be set by \cs{Distance}.
  497.  
  498. You have to set the amount of stretch {\it before} specifying that
  499. the margins will not be flush. The \cs{FlushRight/Left} commands take
  500. the current value whenever they are called.
  501.  
  502. \Section White Space
  503.  
  504. White space can be indicated by \refcs{hwhite} and \refcs{vwhite}.
  505. They are often useful in style definitions. Use:
  506. \Ver>\vwhite:15pt<Rev
  507. or \Ver>\hwhite:{15pt minus 3pt}<Rev
  508. for stretch and shrink. The command \refcs{white} is independent
  509. of the mode, and it expands to \cs{hwhite} or \cs{vwhite} 
  510. depending on the prevailing mode of \TeX.
  511.  
  512. The command \refcs{fillup} is mostly useful in style definitions:
  513. it tries to fill up as much white space as is possible.
  514. For instance
  515. \Ver>    line:start litteral:foo fillup litteral:bar line:stop<Rev
  516. will push \n{foo} and \n{bar} as far apart as is possibly
  517. within the margins.
  518.  
  519. \ImpNote
  520. All three control sequences \cs{white}, \cs{hwhite}, \cs{vwhite}
  521. have internal equivalents, for instance
  522. \Ver>\def\white:#1 {\@white{#1}}<Rev
  523. \ImpNoteStop
  524.  
  525. \Section[sec:com:distance] Distances
  526.  
  527. The command \refcs{Distance} can be used 
  528. to declare a name for a certain
  529. distance, or in more correct \TeX nical lingo, for a certain piece of
  530. glue. For instance, declaring that
  531.  \Ver>\Distance:oneline=15pt<Rev
  532. means that you can specify in some constructs
  533. \Ver>\DefineFoo:Bar whitebefore:oneline whiteafter:oneline<Rev
  534. If you change your mind later about the value of \n{oneline} you only
  535. need to change one line in the style definition.
  536.  
  537. Since the second parameter of \cs{Distance} is bounded by a space (or
  538. the line end, whatever comes first), you can specify stretchable
  539. distances by enclosing \n{plus} and \n{minus} parts in braces:
  540. \Ver>\Distance:oneline={15pt plus 2pt minus 3pt}<Rev
  541.  
  542. The effect of \cs{Distance} is global. Let me know if you don't
  543. like it.
  544.  
  545. \SubSection Distance synonyms
  546.  
  547. Another use of \cs{Distance} is to define one distance as a synonym
  548. of another. This may come in handy if you use some basic distance,
  549. such as \n{oneline} for several purposes. Example: if you specify
  550. \Ver>\Distance:whitebefore=oneline<Rev
  551. than the whitespace before a construct will be taken to be
  552. \n{oneline} if you don't use the \opt{whitebefore} option explicitly.
  553.  
  554. \SubSection[sec:adapt-distance] Adaptive distances
  555.  
  556. Suppose you want to declare a section heading as
  557.  \Ver>\DefineHeading:Section ...
  558.   block:start [...] fillupto:widelabel title<Rev
  559. where \cs{widelabel} is the width of the widest label that
  560. occurs in your document. This requires just a tad of \TeX\
  561. programming. Just copy the details from the example below, which is
  562. the definition of \cs{Section} in this manual.
  563.  
  564. By declaring something a \refcs{AdaptiveDistance} instead of just
  565. \cs{Distance} its value gets written to the \file{.aux} file at the
  566. end of the run, and restored in the next run. The second argument is
  567. simply the default value, in case you don't have an auxiliary file
  568. yet. 
  569.  
  570. \Ver>\AdaptiveDistance:WidestLabel=15pt
  571. \def\MeasureLabel{\ifdim\BlockWidth>\WidestLabel
  572.     \global\WidestLabel\BlockWidth\fi}
  573. \DefineHeading:Section
  574.     whitebefore:{20pt plus 2pt} whiteafter:14pt
  575.     line:start PointSize:14 Style:italic 
  576.         block:start block:start ChapterCounter . SectionCounter
  577.               Spaces:1 block:stop MeasureLabel
  578.               fillupto:WidestLabel
  579.         title line:stop
  580.     external:contents title external:stop
  581.     label:start ChapterCounter . SectionCounter label:stop
  582.     Stop<Rev
  583.  
  584. Note how two nested blocks are used: the first is to measure the
  585. label, and the width is written to the adaptive distance by means of
  586. a small macro; the second block is to fill out the white space.
  587.  
  588. If you want the paragraph indentation to depend on this adaptive
  589. width, you can give
  590.  \Ver>\StartCommand{\Distance:parindent=WidestLabel }<Rev
  591. to set \cs{parindent} at the start of the document.
  592. See section~\ref[sec:doc-start-stop] and~\ref[sec:basic-indent].
  593.  
  594. \Section[sec:InputFile] Input Files
  595.  
  596. Parts of a document can be loaded by
  597. \Ver>\InputFile:parta
  598. \InputFile:partb<Rev
  599. et cetera.  A~document part loaded by \refcs{InputFile} always starts
  600. on a new page. In section~\ref[sec:ref-local] it was already
  601. explained how local references for such files can be created.
  602.  
  603. Perhaps most importantly, loading files this way provides a form of
  604. error checking; \Lollipop\ checks at the end of such a file whether all
  605. used constructs are balanced properly.
  606.  
  607.  
  608. \Section[sec:tests] Tests
  609.  
  610. Users can define tests:
  611. \Ver>\DefineTest:SomethingTheMatter<Rev
  612. which are set like any other test:
  613. \Ver>\SomethingTheMatter:yes<Rev
  614. or \Ver>\SomethingTheMatter:no<Rev
  615.  
  616. Tests can be used as \Ver>\ifSomethingTheMatter ... \else ... \fi<Rev
  617. Like any other conditional, test can be used inside constructs.
  618. \Ver>\DefineFoo:Bar [...]
  619.  ifSomethingTheMatter [...] fi
  620.  [...] Stop<Rev
  621.  
  622. \Section Goodies
  623.  
  624. \SubSection List commands
  625.  
  626. Lollipop does a lot of list processing internally, and a few
  627. of the commands have been made available to the user.
  628.  
  629. \Description\item \refcs{NewList}
  630. creates a list, and sets it to empty:
  631.  \Ver>\NewList:mylist<Rev
  632.  \item \refcs{TheList}
  633. inserts the list. This will typeset the contents of it.
  634.  \Ver>\TheList:mylist<Rev 
  635.  \item \refcs{AppendToList}
  636. adds data to a list. \Ver>\AppendToList:mylist={my data}<Rev
  637. The data are terminated by a space or line end, hence the braces.
  638. \>
  639.  
  640. \SubSection Programming Tools
  641.  
  642. A few commands are useful for the Lollipop style designer who wants
  643. to write more sophisticated macros (see for instance the address book
  644. macros in the last chapter).
  645.  
  646. \Description\item \refcs{UndefinedCS}
  647. is a test on control sequences.
  648.  \Ver>\if\UndefinedCS{testcs} ... \else ... \fi<Rev
  649.  \item \refcs{EqualString}
  650. tests equality of strings.
  651.  \Ver>\if\EqualString{one}{two} ... \else ... \fi<Rev
  652.  \item \refcs{NextChar}
  653. chooses between two actions, based on the next character.
  654.  \Ver>\if\NextChar[{\macro}{\macro[default]} ...<Rev
  655.  \item \refcs{EmptyList}
  656. can test whether an argument is empty.
  657.  \Ver>\if\EmptyList{#1} ...<Rev
  658. is true for calls such as \ver>\macro{}>.
  659. \>
  660.  
  661. \SubSection[sec:everypar] \cs{everypar}
  662.  
  663. The \TeX\ primitive \cs{everypar} should note be used any more.
  664. Instead use the command \refcs{EveryParagraph} as if you are setting
  665. a token list:
  666.  \Ver>\EveryParagraph{ ... }<Rev
  667.  
  668. \SubSection Allocation
  669.  
  670. The commands \refcs{SaveAlloc} and subsequent \refcs{RestoreAlloc} save and
  671. reset the internal \TeX\ allocation counters.
  672.  
  673. 92/11/18 Adaptive distances explained
  674. 92/11/20 Adaptive counters explained
  675.